<html>
    <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>Hammerspoon docs: OBS</title>
    <style type="text/css">
      a { text-decoration: none; }
      a:hover { text-decoration: underline; }
      th { background-color: #DDDDDD; vertical-align: top; padding: 3px; }
      td { width: 100%; background-color: #EEEEEE; vertical-align: top; padding: 3px; }
      table { width: 100% ; border: 1px solid #0; text-align: left; }
      section > table table td { width: 0; }
    </style>
    <link rel="stylesheet" href="docs.css" type="text/css" media="screen" />
  </head>
  <body>
    <header>
      <h1><a href="./index.html">docs</a> &raquo; OBS</h1>
      <p>Control OBS and react to its events, via the obs-websocket plugin.</p>
<p>Install and configure the obs-websocket plugin first from <a href="https://github.com/obsproject/obs-websocket/releases">their project</a></p>
<p>Note: This Spoon will only work with Hammerspoon 0.9.100 or later.</p>
<p>Note: This Spoon will only work with obs-websocket 5.0.1 or later, which also requires OBS Studio v27 or later.</p>
<p>Download: <a href="https://github.com/Hammerspoon/Spoons/raw/master/Spoons/OBS.spoon.zip">https://github.com/Hammerspoon/Spoons/raw/master/Spoons/OBS.spoon.zip</a></p>
<p>Example:</p>

<pre><code>-- This example will start OBS, connect to it, and then start streaming once connected
obs = hs.loadSpoon(&quot;OBS&quot;)
obsCallback = function(eventType, eventIntent, eventData)
  print(eventType)
  print(eventIntent)
  print(hs.inspect(eventData))

  if eventType == &quot;SpoonOBSConnected&quot; then
    obs:request(&quot;StartStream&quot;)
  end
end
obs:init(obsCallback, &quot;localhost&quot;, 4444, &quot;password&quot;)
obs:start()
</code></pre>

      </header>
      <h3>API Overview</h3>
      <ul>
        <li>Constants - Useful values which cannot be changed</li>
          <ul>
            <li><a href="#eventSubscriptionValues">eventSubscriptionValues</a></li>
          </ul>
        <li>Variables - Configurable values</li>
          <ul>
            <li><a href="#reconnectDelay">reconnectDelay</a></li>
            <li><a href="#shouldReconnect">shouldReconnect</a></li>
          </ul>
        <li>Methods - API calls which can only be made on an object returned by a constructor</li>
          <ul>
            <li><a href="#addEventSubsciption">addEventSubsciption</a></li>
            <li><a href="#init">init</a></li>
            <li><a href="#removeEventSubsciption">removeEventSubsciption</a></li>
            <li><a href="#request">request</a></li>
            <li><a href="#requestBatch">requestBatch</a></li>
            <li><a href="#setLogLevel">setLogLevel</a></li>
            <li><a href="#start">start</a></li>
            <li><a href="#stop">stop</a></li>
            <li><a href="#updateEventSubscriptions">updateEventSubscriptions</a></li>
          </ul>
      </ul>
      <h3>API Documentation</h3>
        <h4 class="documentation-section">Constants</h4>
          <section id="eventSubscriptionValues">
            <a name="//apple_ref/cpp/Constant/eventSubscriptionValues" class="dashAnchor"></a>
            <h5><a href="#eventSubscriptionValues">eventSubscriptionValues</a></h5>
            <table>
              <tr>
                <th>Signature</th>
                <td><code>OBS.eventSubscriptionValues</code></td>
              </tr>
              <tr>
                <th>Type</th>
                <td>Constant</td>
              </tr>
              <tr>
                <th>Description</th>
                <td><p>A table of the possible values for the <code>eventSubscriptions</code> parameter to <a href="#init">OBS:init()</a></p>
</td>
              </tr>
              <tr>
                  <th>Notes</th>
                  <td><ul>
<li>The keys are:<ul>
<li><code>None</code> - No events</li>
<li><code>General</code> - General events</li>
<li><code>Config</code> - Configuration events</li>
<li><code>Scenes</code> - Scene events</li>
<li><code>Inputs</code> - Input events</li>
<li><code>Transitions</code> - Transition events</li>
<li><code>Filters</code> - Filter events</li>
<li><code>Outputs</code> - Output events</li>
<li><code>SceneItems</code> - Scene item events</li>
<li><code>MediaInputs</code> - Media input events</li>
<li><code>Vendors</code> - Vendor events</li>
<li><code>UI</code> - UI events</li>
<li><code>All</code> - All of the above events</li>
<li><code>InputVolumeMeters</code> - Input volume meter events</li>
<li><code>InputActiveStateChanged</code> - Input active state changed events</li>
<li><code>InputShowStateChanged</code> - Input show state changed events</li>
<li><code>SceneItemTransformChanged</code> - Scene item transform changed events</li>
</ul>
</li>
<li>For more information about these event categories and the events they contain, see the <a href="https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md#events">obs-websocket documentation</a></li>
<li>To combine these as a bitmask, use boolean operators, e.g. <code>OBS.eventSubscriptionValues.General | OBS.eventSubscriptionValues.Scenes</code></li>
<li>The final four values are considered &quot;high volume&quot; events, so are not included in <code>OBS.eventSubscriptionValues.All</code> by default</li>
</ul>
</td>
              </tr>
              <tr>
                <th>Source</th>
                <td><a href="https://github.com/Hammerspoon/Spoons/blob/master/Source/OBS.spoon/init.lua#L58">Source/OBS.spoon/init.lua line 58</a></td>
              </tr>
            </table>
          </section>
        <h4 class="documentation-section">Variables</h4>
          <section id="reconnectDelay">
            <a name="//apple_ref/cpp/Variable/reconnectDelay" class="dashAnchor"></a>
            <h5><a href="#reconnectDelay">reconnectDelay</a></h5>
            <table>
              <tr>
                <th>Signature</th>
                <td><code>OBS:reconnectDelay</code></td>
              </tr>
              <tr>
                <th>Type</th>
                <td>Variable</td>
              </tr>
              <tr>
                <th>Description</th>
                <td><p>Controls how long to wait, in seconds, before attempting to reconnect to OBS. Defaults to <code>5</code></p>
</td>
              </tr>
              <tr>
                <th>Source</th>
                <td><a href="https://github.com/Hammerspoon/Spoons/blob/master/Source/OBS.spoon/init.lua#L112">Source/OBS.spoon/init.lua line 112</a></td>
              </tr>
            </table>
          </section>
          <section id="shouldReconnect">
            <a name="//apple_ref/cpp/Variable/shouldReconnect" class="dashAnchor"></a>
            <h5><a href="#shouldReconnect">shouldReconnect</a></h5>
            <table>
              <tr>
                <th>Signature</th>
                <td><code>OBS:shouldReconnect</code></td>
              </tr>
              <tr>
                <th>Type</th>
                <td>Variable</td>
              </tr>
              <tr>
                <th>Description</th>
                <td><p>Controls whether the websocket connection should be re-established if it is lost. Defaults to <code>true</code></p>
</td>
              </tr>
              <tr>
                <th>Source</th>
                <td><a href="https://github.com/Hammerspoon/Spoons/blob/master/Source/OBS.spoon/init.lua#L105">Source/OBS.spoon/init.lua line 105</a></td>
              </tr>
            </table>
          </section>
        <h4 class="documentation-section">Methods</h4>
          <section id="addEventSubsciption">
            <a name="//apple_ref/cpp/Method/addEventSubsciption" class="dashAnchor"></a>
            <h5><a href="#addEventSubsciption">addEventSubsciption</a></h5>
            <table>
              <tr>
                <th>Signature</th>
                <td><code>OBS:addEventSubsciption(event)</code></td>
              </tr>
              <tr>
                <th>Type</th>
                <td>Method</td>
              </tr>
              <tr>
                <th>Description</th>
                <td><p>Adds an event subscription</p>
</td>
              </tr>
              <tr>
                  <th>Parameters</th>
                  <td><ul>
<li><code>event</code> - The event to subscribe to, see <a href="#eventSubscriptionValues">OBS.eventSubscriptionValues</a></li>
</ul>
</td>
              </tr>
              <tr>
                  <th>Returns</th>
                  <td><ul>
<li>None</li>
</ul>
</td>
              </tr>
              <tr>
                  <th>Notes</th>
                  <td><ul>
<li>If you wish to add multiple event subscriptions you can use the <code>|</code> operator to combine them, e.g. <code>spoon.OBS:addEventSubscription(spoon.OBS.eventSubscriptionValues.Config | spoon.OBS.eventSubscriptionValues.Scenes)</code></li>
</ul>
</td>
              </tr>
              <tr>
                <th>Source</th>
                <td><a href="https://github.com/Hammerspoon/Spoons/blob/master/Source/OBS.spoon/init.lua#L309">Source/OBS.spoon/init.lua line 309</a></td>
              </tr>
            </table>
          </section>
          <section id="init">
            <a name="//apple_ref/cpp/Method/init" class="dashAnchor"></a>
            <h5><a href="#init">init</a></h5>
            <table>
              <tr>
                <th>Signature</th>
                <td><code>OBS:init(eventCallback, host, port[, password, eventSubscriptions])</code></td>
              </tr>
              <tr>
                <th>Type</th>
                <td>Method</td>
              </tr>
              <tr>
                <th>Description</th>
                <td><p>Initialisation method</p>
</td>
              </tr>
              <tr>
                  <th>Parameters</th>
                  <td><ul>
<li><code>eventCallback</code> - A function to be called when an event is received from OBS. The function will be passed a table containing the event data. The keys of the table are:<ul>
<li><code>eventType</code> - The type of event, e.g. <code>StudioModeStateChanged</code></li>
<li><code>eventIntent</code> - The event subscription value that caused this event to be sent, e.g. <code>OBS.eventSubscriptionValues.General</code></li>
<li><code>eventData</code> - A table containing the event data, e.g. <code>{ &quot;studioModeEnabled&quot;: true }</code></li>
</ul>
</li>
<li><code>host</code> - The hostname or IP address of the machine running OBS</li>
<li><code>port</code> - The port number that obs-websocket is listening on</li>
<li><code>password</code> - An optional password string that obs-websocket is configured to use</li>
<li><code>eventSubscriptions</code> - An optional number containing the bitmask of the events to subscribe to, see <a href="#eventSubscriptionValues">OBS.eventSubscriptionValues</a></li>
</ul>
</td>
              </tr>
              <tr>
                  <th>Returns</th>
                  <td><ul>
<li>None</li>
</ul>
</td>
              </tr>
              <tr>
                  <th>Notes</th>
                  <td><ul>
<li>This method does not connect to OBS, it just sets up the connection parameters for later use</li>
<li>By default, no events are subscribed to, so you will need to set <code>eventSubscriptions</code> to something useful if you want to receive events</li>
<li>If you do not wish to supply an <code>eventCallback</code>, pass <code>nil</code> instead</li>
<li>The events that OBS can produce are documented in the <a href="https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md#events">obs-websocket documentation</a></li>
<li>There are some additional values for <code>eventType</code>, specific to this Spoon:<ul>
<li><code>SpoonOBSConnected</code> - This event is sent when the websocket connection to OBS is established. All other fields will be <code>nil</code>.</li>
<li><code>SpoonOBSDisconnected</code> - This event is sent when the websocket connection to OBS is lost. All other fields will be nil. Return false to inhibit automatic reconnection.</li>
<li><code>SpoonRequestResponse</code> - This event is sent to pass replies to requests made via <a href="#request">OBS:request()</a>. Its <code>eventIntent</code> will be nil and the format of its <code>eventData</code> table will be:<ul>
<li><code>requestId</code> - The ID of the request that this is a reply to</li>
<li><code>requestType</code> - The request type that was made</li>
<li><code>requestStatus</code> - A table containing:<ul>
<li><code>result</code> - A bool, <code>true</code> if the request succeeded, otherwise <code>false</code></li>
<li><code>code</code> - A number containing the response code</li>
<li><code>comment</code> - An optional string that may contain additional information about the response</li>
</ul>
</li>
<li><code>responseData</code> - An table that contains the response data, if any</li>
</ul>
</li>
<li><code>SpoonBatchRequestResponse</code> - This event is sent to pass replies to batch requests made via <a href="#requestBatch">OBS:requestBatch()</a>. Its <code>eventIntent</code> will be nil and the format of its <code>eventData</code> table will be:<ul>
<li><code>requestId</code> - The ID of the request batch that this is a reply to</li>
<li><code>results</code> - A table containing the results of each request in the batch. Each entry in the table will be a table with the same format as <code>SpoonRequestResponse</code></li>
</ul>
</li>
</ul>
</li>
</ul>
</td>
              </tr>
              <tr>
                <th>Source</th>
                <td><a href="https://github.com/Hammerspoon/Spoons/blob/master/Source/OBS.spoon/init.lua#L117">Source/OBS.spoon/init.lua line 117</a></td>
              </tr>
            </table>
          </section>
          <section id="removeEventSubsciption">
            <a name="//apple_ref/cpp/Method/removeEventSubsciption" class="dashAnchor"></a>
            <h5><a href="#removeEventSubsciption">removeEventSubsciption</a></h5>
            <table>
              <tr>
                <th>Signature</th>
                <td><code>OBS:removeEventSubsciption(event)</code></td>
              </tr>
              <tr>
                <th>Type</th>
                <td>Method</td>
              </tr>
              <tr>
                <th>Description</th>
                <td><p>Removes an event subscription</p>
</td>
              </tr>
              <tr>
                  <th>Parameters</th>
                  <td><ul>
<li><code>event</code> - The event to unsubscribe from, see <a href="#eventSubscriptionValues">OBS.eventSubscriptionValues</a></li>
</ul>
</td>
              </tr>
              <tr>
                  <th>Returns</th>
                  <td><ul>
<li>None</li>
</ul>
</td>
              </tr>
              <tr>
                  <th>Notes</th>
                  <td><ul>
<li>If you wish to remove multiple event subscriptions you can use the <code>&amp;</code> operator to combine them, e.g. <code>spoon.OBS:removeEventSubscription(spoon.OBS.eventSubscriptionValues.Config | spoon.OBS.eventSubscriptionValues.Scenes)</code></li>
</ul>
</td>
              </tr>
              <tr>
                <th>Source</th>
                <td><a href="https://github.com/Hammerspoon/Spoons/blob/master/Source/OBS.spoon/init.lua#L326">Source/OBS.spoon/init.lua line 326</a></td>
              </tr>
            </table>
          </section>
          <section id="request">
            <a name="//apple_ref/cpp/Method/request" class="dashAnchor"></a>
            <h5><a href="#request">request</a></h5>
            <table>
              <tr>
                <th>Signature</th>
                <td><code>OBS:request(requestType[, requestData[, requestId]])</code></td>
              </tr>
              <tr>
                <th>Type</th>
                <td>Method</td>
              </tr>
              <tr>
                <th>Description</th>
                <td><p>Sends a request to OBS</p>
</td>
              </tr>
              <tr>
                  <th>Parameters</th>
                  <td><ul>
<li><code>requestType</code> - A string containing the type of request to send</li>
<li><code>requestData</code> - An optional table containing the data to send with the request, or nil</li>
<li><code>requestId</code> - An optional string containing the ID of the request</li>
</ul>
</td>
              </tr>
              <tr>
                  <th>Returns</th>
                  <td><ul>
<li>The <code>requestId</code> that was sent</li>
</ul>
</td>
              </tr>
              <tr>
                  <th>Notes</th>
                  <td><ul>
<li>If <code>requestId</code> is not specified then a random UUID will be generated.</li>
<li>The <code>requestId</code> will be passed to your event callback (provided to <a href="#init">OBS:init()</a>) when the response is received.</li>
<li>Values for <code>requestType</code> can be found in the <a href="https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md#requests">obs-websocket documentation</a></li>
</ul>
</td>
              </tr>
              <tr>
                <th>Source</th>
                <td><a href="https://github.com/Hammerspoon/Spoons/blob/master/Source/OBS.spoon/init.lua#L343">Source/OBS.spoon/init.lua line 343</a></td>
              </tr>
            </table>
          </section>
          <section id="requestBatch">
            <a name="//apple_ref/cpp/Method/requestBatch" class="dashAnchor"></a>
            <h5><a href="#requestBatch">requestBatch</a></h5>
            <table>
              <tr>
                <th>Signature</th>
                <td><code>OBS:requestBatch(requests[, haltOnFailure])</code></td>
              </tr>
              <tr>
                <th>Type</th>
                <td>Method</td>
              </tr>
              <tr>
                <th>Description</th>
                <td><p>Sends a batch of requests to OBS</p>
</td>
              </tr>
              <tr>
                  <th>Parameters</th>
                  <td><ul>
<li><code>requests</code> - A table containing the requests to send</li>
<li><code>haltOnFailure</code> - An optional boolean indicating whether to halt the batch if a request fails, defaults to false</li>
</ul>
</td>
              </tr>
              <tr>
                  <th>Returns</th>
                  <td><ul>
<li>The <code>requestId</code> that was sent for the batch</li>
</ul>
</td>
              </tr>
              <tr>
                  <th>Notes</th>
                  <td><ul>
<li>Each request should be a table with the keys:<ul>
<li><code>requestType</code> - A string containing the type of request to send, see <a href="#request">OBS:request()</a></li>
<li><code>requestData</code> - An optional table containing the data to send with the request, or <code>nil</code></li>
<li><code>requestId</code> - An optional string containing a unique ID for the request</li>
</ul>
</li>
<li>Unlike <a href="#request">OBS:request()</a> the <code>requestId</code> is an auto-generated UUID</li>
</ul>
<p>Example:</p>
<div class="highlight"><pre><span></span><span class="n">spoon</span><span class="p">.</span><span class="n">OBS</span><span class="p">:</span><span class="n">requestBatch</span><span class="p">({</span>
 <span class="p">{[</span><span class="s2">&quot;requestType&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="s2">&quot;StartVirtualCam&quot;</span><span class="p">},</span>
 <span class="p">{[</span><span class="s2">&quot;requestType&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="s2">&quot;SetCurrentProgramScene&quot;</span><span class="p">,</span> <span class="p">[</span><span class="s2">&quot;requestData&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="p">{</span> <span class="p">[</span><span class="s2">&quot;sceneName&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="s2">&quot;FancyScene&quot;</span> <span class="p">}}</span>
<span class="p">})</span>
</pre></div>
</td>
              </tr>
              <tr>
                <th>Source</th>
                <td><a href="https://github.com/Hammerspoon/Spoons/blob/master/Source/OBS.spoon/init.lua#L377">Source/OBS.spoon/init.lua line 377</a></td>
              </tr>
            </table>
          </section>
          <section id="setLogLevel">
            <a name="//apple_ref/cpp/Method/setLogLevel" class="dashAnchor"></a>
            <h5><a href="#setLogLevel">setLogLevel</a></h5>
            <table>
              <tr>
                <th>Signature</th>
                <td><code>OBS:setLogLevel(level)</code></td>
              </tr>
              <tr>
                <th>Type</th>
                <td>Method</td>
              </tr>
              <tr>
                <th>Description</th>
                <td><p>Sets the logging level for the OBS Spoon</p>
</td>
              </tr>
              <tr>
                  <th>Parameters</th>
                  <td><ul>
<li><code>level</code> - A string containing the logging level to use, see <a href="https://www.hammerspoon.org/docs/hs.logger.html#setLogLevel">hs.logger.setLogLevel</a> for possible values</li>
</ul>
</td>
              </tr>
              <tr>
                  <th>Returns</th>
                  <td><ul>
<li>None</li>
</ul>
</td>
              </tr>
              <tr>
                <th>Source</th>
                <td><a href="https://github.com/Hammerspoon/Spoons/blob/master/Source/OBS.spoon/init.lua#L419">Source/OBS.spoon/init.lua line 419</a></td>
              </tr>
            </table>
          </section>
          <section id="start">
            <a name="//apple_ref/cpp/Method/start" class="dashAnchor"></a>
            <h5><a href="#start">start</a></h5>
            <table>
              <tr>
                <th>Signature</th>
                <td><code>OBS:start()</code></td>
              </tr>
              <tr>
                <th>Type</th>
                <td>Method</td>
              </tr>
              <tr>
                <th>Description</th>
                <td><p>Connects to OBS</p>
</td>
              </tr>
              <tr>
                  <th>Parameters</th>
                  <td><ul>
<li>None</li>
</ul>
</td>
              </tr>
              <tr>
                  <th>Returns</th>
                  <td><ul>
<li>None</li>
</ul>
</td>
              </tr>
              <tr>
                <th>Source</th>
                <td><a href="https://github.com/Hammerspoon/Spoons/blob/master/Source/OBS.spoon/init.lua#L161">Source/OBS.spoon/init.lua line 161</a></td>
              </tr>
            </table>
          </section>
          <section id="stop">
            <a name="//apple_ref/cpp/Method/stop" class="dashAnchor"></a>
            <h5><a href="#stop">stop</a></h5>
            <table>
              <tr>
                <th>Signature</th>
                <td><code>OBS:stop()</code></td>
              </tr>
              <tr>
                <th>Type</th>
                <td>Method</td>
              </tr>
              <tr>
                <th>Description</th>
                <td><p>Disconnects from OBS</p>
</td>
              </tr>
              <tr>
                  <th>Parameters</th>
                  <td><ul>
<li>None</li>
</ul>
</td>
              </tr>
              <tr>
                  <th>Returns</th>
                  <td><ul>
<li>None</li>
</ul>
</td>
              </tr>
              <tr>
                <th>Source</th>
                <td><a href="https://github.com/Hammerspoon/Spoons/blob/master/Source/OBS.spoon/init.lua#L274">Source/OBS.spoon/init.lua line 274</a></td>
              </tr>
            </table>
          </section>
          <section id="updateEventSubscriptions">
            <a name="//apple_ref/cpp/Method/updateEventSubscriptions" class="dashAnchor"></a>
            <h5><a href="#updateEventSubscriptions">updateEventSubscriptions</a></h5>
            <table>
              <tr>
                <th>Signature</th>
                <td><code>OBS:updateEventSubscriptions(eventSubscriptions)</code></td>
              </tr>
              <tr>
                <th>Type</th>
                <td>Method</td>
              </tr>
              <tr>
                <th>Description</th>
                <td><p>Updates the event subscriptions</p>
</td>
              </tr>
              <tr>
                  <th>Parameters</th>
                  <td><ul>
<li><code>eventSubscriptions</code> - A bitmask of the events to subscribe to, see <a href="#eventSubscriptionValues">OBS.eventSubscriptionValues</a></li>
</ul>
</td>
              </tr>
              <tr>
                  <th>Returns</th>
                  <td><ul>
<li>None</li>
</ul>
</td>
              </tr>
              <tr>
                <th>Source</th>
                <td><a href="https://github.com/Hammerspoon/Spoons/blob/master/Source/OBS.spoon/init.lua#L289">Source/OBS.spoon/init.lua line 289</a></td>
              </tr>
            </table>
          </section>
  </body>
</html>